home *** CD-ROM | disk | FTP | other *** search
/ Amiga Games: Greatest Hits 1996 / Amiga Games: Greatest Hits 1996.iso / archive / userbox / publicdomain / superviewel.lha / SuperViewEL / SuperViewLibrary / Docs / SVSupport-Docs / CPInfoFormat.doc < prev    next >
Text File  |  1996-06-18  |  9KB  |  231 lines
  1.  
  2.   The ControlPadInfo-FileFormat V12.5 (2.12.95)
  3.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  4.   Some applications might wish to enable the user to interactively
  5.   specify controlpad settings just when reading, writing or
  6.   processing an image and not before or after by setting preferences.
  7.  
  8.   Until this will be managed by superview.library, superviewsupport.library
  9.   or the single modules by introducing new functions for handling this,
  10.   applications may take this information from ".cpinfo" files, where
  11.   the specific ControlPad entries are dynamically described.
  12.  
  13.    Content
  14.    =======
  15.     - Structure in general
  16.     - Structure in detail
  17.     - Structure Entry Description in detail
  18.     - Examples
  19.     - Last Words and Exceptions
  20.     - Future
  21.     - Special configuration Standards
  22.  
  23.  
  24.   Structure in general
  25.   --------------------
  26.   Every CPInfo-File is constructed like an usual ControlPad file,
  27.   but in this case, the _order_ of the entries becomes meaningful.
  28.   These files are separated into SECTIONs, where any necessary
  29.   information about specific ControlPad entries are stored.
  30.  
  31.   To allow easy enhancements and improvements on this format, there's
  32.   an important note:
  33.  
  34.       - the number of sections is not limited
  35.       - each SECTION _must_ contain at least the entries described below
  36.       - each SECTION _may_ contain more entries, so that it might be
  37.         necessary to skip all the following entries until another "SECTION"
  38.         entry will be reached
  39.       - the order of the entries is _fixed_
  40.       - if any of the following _needed_ entries makes no sense,
  41.         it will still be present as a "dummy", thus just a Keyword
  42.         is placed there and no value is given via "="
  43.       - any single line should not exceed 255 characters
  44.       - as with usual ControlPad files, comments and blank lines are allowed
  45.  
  46.   Structure in detail
  47.   -------------------
  48.       CPINFO                               ; identification
  49.       SECTION=<Name of ControlPad entry>   ; the name of the entry
  50.       TYPE=<INTEGER|FLOAT|ASCII|NONE>      ; type of data
  51.                                            ; (signed or unsigned for
  52.                                            ;  INTEGER or FLOAT may
  53.                                            ;  be detected via MIN and MAX).
  54.                                            ; NONE is used for KeyWords.
  55.       MIN=<Value>                          ; - minimum value for numbers
  56.                                            ; - minimum length for strings
  57.                                            ; - or empty ("MIN")
  58.                                            ; Empty with KeyWords.
  59.       MAX=<Value>                          ; - maximum value for numbers
  60.                                            ; - maximum length for strings
  61.                                            ; - or empty ("MAX")
  62.                                            ; Empty with KeyWords.
  63.       DEFAULT=<Default value for entry>    ; what will be used if nothing
  64.                                            ; is specified ?!
  65.                                            ; Empty e.g. with KeyWords.
  66.       DESCRIPTION=<descriptive text>       ; what does it do ?
  67.       MASK=<input mask>                    ; this one allows to separate
  68.                                            ; choices and "free" enterings
  69.                                            ; Empty with KeyWords.
  70.       WHEN=<READ|WRITE|ALWAYS|PREFS|NEVER> ; ask for it, when the user
  71.                                            ; does reading or writing
  72.                                            ; (SVObjects) ? Or always
  73.                                            ; (SVDrivers/SVOperators) ?
  74.                                            ; Or never ? (Undocumented)
  75.                                            ; Or Just handle it as a real
  76.                                            ; preferences thing ?
  77.  
  78.     Structure Entry Description in detail
  79.     -------------------------------------
  80.     o A few words to the MASK entry:
  81.  
  82.       Any entries which don't have a specific meaning (just comments)
  83.       or mutual exclude entries do have to begin with "<" and end with
  84.       ">". Anything else are control sequences, qhich either are
  85.       to be supported or have to be ignored.
  86.  
  87.       a) "<...>" or "<...|...|...>"
  88.  
  89.       Usually you should print out this text as a little help for
  90.       the user, how to enter the data, e.g. into a string/integer gadget.
  91.       But if the string included by "<" and ">" does contain one or
  92.       more "|" these are meant as exclusice choices, which e.g.
  93.       might be represented as mx-, cycle- or listview-gadgets.
  94.       So you may a) present this mask to the user while editing a
  95.       string/integer gadget or b) parse it and just "filter" the input
  96.       via supplying appropriate input gadgets.
  97.       Please note, that the "MIN" and "MAX" values (if specified)
  98.       still have to be valid for this input (if the file definition
  99.       has been done correctly ;-)
  100.       So for a "MASK=<8|24>" these would equal "MIN=8" and "MAX=24".
  101.       But note, that this "mask" is not really meant to define ranges
  102.       with gaps, like "anything between 5 and 37, but except the numbers
  103.       between 33.3 und 36.5" 8-)
  104.  
  105.       b) Control Sequences
  106.  
  107.       MASK=_SVOBJECT                means, that a file from "LIBS:svobjects"
  108.                                     has to be requested, which matches
  109.                                     "#?.svobject".
  110.       MASK=_SVDRIVER                means, that a file from "LIBS:svdrivers"
  111.                                     has to be requested, which matches
  112.                                     "#?.svdriver".
  113.       MASK=_SVOPERATOR              means, that a file from "LIBS:svoperators"
  114.                                     has to be requested, which matches
  115.                                     "#?.svoperator".
  116.       MASK=_FILE                    a file to be selected e.g. fromout a
  117.                                     requester (it is supposed, that the user
  118.                                     does the right choice).
  119.  
  120.     Examples
  121.     --------
  122.  
  123.     Anentry for a KeyWord might look like this:
  124.  
  125.     SECTION=ANYDATATYPES
  126.     TYPE=NONE
  127.     MIN
  128.     MAX
  129.     DEFAULT
  130.     DESCRIPTION=Switches Datatypes support to ANY
  131.     MASK
  132.     WHEN=PREFS
  133.  
  134.  
  135.     An entry for a float value:
  136.  
  137.     SECTION=SCALE_FACTOR
  138.     TYPE=FLOAT
  139.     MIN=0.1
  140.     MAX=2.0
  141.     DEFAULT=1.0
  142.     DESCRIPTION=Factor for scaling graphics
  143.     MASK=<Value>
  144.     WHEN=ALWAYS
  145.  
  146.  
  147.     An entry for an ASCII text:
  148.  
  149.     SECTION=PACKMETHOD
  150.     TYPE=ASCII
  151.     MIN=4
  152.     MAX=4
  153.     DEFAULT=NUKE
  154.     DESCRIPTION=How to pack the written data
  155.     MASK=<XPK-Packer>
  156.     WHEN=WRITE
  157.  
  158.  
  159.     An example for an ignoreable Keyword:
  160.  
  161.     SECTION=DEBUGMODE
  162.     TYPE=NONE
  163.     MIN
  164.     MAX
  165.     DEFAULT
  166.     DESCRIPTION=Enables debugging mode with Confirm-Requesters
  167.     MASK
  168.     WHEN=NEVER
  169.  
  170.  
  171.   Last Words and Exceptions
  172.   -------------------------
  173.   So you see, that it's easy to describe any of the existing ControlPad
  174.   variations this way.
  175.  
  176.   The "WHEN" statement is a help for applications to decide, whether
  177.   and when to allow changing of specific ControlPad entries.
  178.  
  179.   Applications should either ignore entries of type "WHEN=NEVER"
  180.   or prepared to handle slightly differing entries, like
  181.   e.g. TYPE=INTEGER entries with a non-set default value.
  182.   (An example had been the "AVAILMEM" switch of interim versions
  183.    of JPEG.svobject - which was both: a keyword and a common setting,
  184.    but should never be changed during runtime.)
  185.  
  186.   "WHEN=NEVER" is just for options with experimental state or
  187.   debugging purposes.
  188.  
  189.  
  190.   Future
  191.   ------
  192.   In the future, there may be a function in superview.library, which
  193.   allows passing a controlpad list to it, which then may be passed
  194.   to the attached SVObject/SVDriver/SVOperator as a "local" setting,
  195.   which will override the "global" ControlPad files.
  196.  
  197.   So the CPInfo Files will be helpful for applications on how
  198.   to find out, which ControlPads might be possibly set.
  199.  
  200.  
  201.   Special configuration Standards
  202.   -------------------------------
  203.   For special cases it seems to be suitable to define a common
  204.   behavior, so that GUI-based and interactive selections for
  205.   those special cases may become independent from specific modules.
  206.  
  207.     Applying operations to parts of images only (crop standard)
  208.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  209.     Suggested by Steve Quartly in 11/95
  210.  
  211.      Operators and other modules, which allow to apply their specific
  212.      operations to either the whole given image or only a defined
  213.      part of it, should use the following controlpads as a standard
  214.      for allowing the application to better visualize the process
  215.      of selecting the concerned parts of the graphics.
  216.  
  217.       REGION=<ENTIREIMAGE|RECTANGULAR>
  218.         ; if this one exists, you have the choice.
  219.         ; Then, if REGION=ENTIREIMAGE, the following are supposed to be
  220.         ; 0, 0, width, height, otherwise they have to be specified.
  221.       LEFTEDGE=<Value smaller or equal width>
  222.       TOPEDGE=<Value smaller or equal height>
  223.       WIDTH=<width of shape>
  224.       HEIGHT=<height of shape>
  225.         ; just like opening a window
  226.  
  227. --
  228. Andy, 2.12.95
  229.  
  230.  
  231.